kc3-lang/libxkbcommon/doc

doc

Log

Author Commit Date CI Message
Pierre Le Marre f7a61da7 2025-06-10T17:33:24 doc: Update new layout count ranges
Pierre Le Marre 6d67bce5 2025-06-08T10:01:02 doc: Towards and exhaustive compatibility page We need to track the compatibility with X11 with as much details as possible: - Transparency; - Facilitate answering issues by just pointing to the relevant page item; - Efficient reference documentation for development.
Pierre Le Marre 27ba56ae 2025-05-07T10:55:24 doc: Add initial documention for XKB_KEYMAP_FORMAT_TEXT_V2
Pierre Le Marre 58397e94 2025-05-06T18:05:30 Deprecate xkb_keymap_new_from_names() - Deprecate `xkb_keymap_new_from_names()` in favor of `xkb_keymap_new_from_names2()` - Add new changelog fragment type `deprecated`. - Change documentation to use the new function.
Pierre Le Marre 39b4b670 2025-06-06T18:40:29 Support including keymap components using %-expansion and absolute path Enable to use the same `include` features than *rules* files in *keymap components*: - *`%`-expansion*: `%H` home directory, `%S` sytem root and `%E` extra. - absolute file paths. This is useful if one wants to overwrite the system file with a user config (i.e. same name, but in `~/.config/xkb`), but still include the system file: ``` // File: ~/.config/xkb/symbols/de xkb_symbols "basic" { include "%S/de(basic)" key <AB01> { [z, Z] }; key <AD06> { [y, Y] }; } ```` Without the commit, using a mere `include "de(basic)"` would result in an include loop. Refactored by using the same code for rules and keymap components.
Pierre Le Marre 324984f1 2025-05-17T06:49:49 xkbcomp: Fix log for unknown default field
Pierre Le Marre fb9fec18 2025-05-10T10:18:38 xkbcomp: Checked arithmetic Use a polyfill for C23 checked arithmetic. This is a bit paranoid, as we expect the user to use only 32 bit integers, so the signed 64 bit integer we use to store the result should be more than enough. Use jtckdint v1.0: - repository: https://github.com/jart/jtckdint - commit: 339450d13d8636f05dcb71ba36efddb226db481e - removed all C++-specific code
Pierre Le Marre 9da1a2eb 2025-05-16T10:33:43 doc: Add license in generated doc
Pierre Le Marre d018638d 2025-05-16T09:35:39 doc: Improve CSS
Pierre Le Marre 61a1e646 2025-05-15T17:24:50 doc: Reformat release notes and include them in the HTML doc
Pierre Le Marre bd552642 2025-05-15T17:20:44 doc: Use custom alias to fix HTML tags unsupported by Doxygen Previous solution with `sed` is both overkilled and unreliable. Prefer a hack using Doxygen’s buit-ins, although we are not sure these are much more stable… 😓
Pierre Le Marre 06fbe1b2 2025-05-14T20:08:39 doc: Promote xkbcli tools
Pierre Le Marre cedc54d0 2025-05-13T15:58:52 doc: Modifier declaration and binding Detailed explanation of: - modifier declaration - real/virtual modifier maps - modifier key binding - modifier encoding - modifier portability
Pierre Le Marre 3eaf8ad2 2025-05-14T18:39:11 doc: Add FAQ section for legacy X tools replacement
Pierre Le Marre 7cf3d49b 2025-05-11T18:21:07 doc: Improve actions - Improve parameters doc of supported actions - Document some legacy actions
Pierre Le Marre 22d27277 2025-05-10T10:12:31 actions: Reject arguments if they are not expected `NoAction`, `VoidAction` and `TerminateServer` do not accept arguments.
Pierre Le Marre d239a3f0 2025-05-11T11:42:20 actions: Improve unsupported legacy X11 actions handling - Display a warning - Document drawbacks of degrading to `NoAction()`
Pierre Le Marre 137c5e90 2025-05-11T12:37:23 actions: Improve unknown action logging
Pierre Le Marre b4c89600 2025-05-09T15:15:10 actions: Add VoidAction(), mirroring NoSymbol/VoidSymbol. Added `VoidAction()` action to match the keysym pair `NoSymbol` / `VoidSymbol`. It enables overriding a previous action and breaks latches. This is a libxkbcommon extension. When serializing it will be converted to `LockControls(controls=none,affect=neither)` for backward compatibility. We cannot serialize it to `NoAction()`, as it would be dropped in e.g. the context of multiple actions.
Pierre Le Marre 7cd1180b 2025-05-06T11:07:47 modifiers: Add xkb_keymap_mod_get_mask() Added a dedicated API to query modifier masks rather than relying on a hack using `xkb_state_update_mask` and `xkb_state_serialize_mods`. Furthermore, this hack may not work in the future if we remove virtual mods resolution in `xkb_state_update_mask` to avoid corner-cases issues.
Pierre Le Marre 9ffe3cfc 2025-04-29T12:48:10 doc: Create a FAQ page - Initialize with multiple recurrent questions. - Document how to get the vmod → rmod mapping. Rational: Some applications may need it to interface with legacy code.
Pierre Le Marre 8af09d59 2025-04-28T07:01:42 doc: Fix usual vmods mapping typo `LevelThree` and `LevelFive` are mapped respectively to `Mod5` and `Mod3`. This is counter-intuitive but set so for ages and probably hard- coded in some places.
Ran Benita 33bc8c13 2025-04-27T11:51:58 doc/keymap-format-text-v1: fix inaccurate statement in Keysym glossary entry Signed-off-by: Ran Benita <ran@unusedvar.com>
Pierre Le Marre 38322758 2025-04-12T13:06:05 doc: Include and merge modes
Pierre Le Marre 9b0b8c68 2025-04-15T19:53:28 xkbcomp: Stricter handling of default map include Before this commit, including a *default* map, i.e. without an explicit section name (e.g. `include "au"` vs `include "au(basic)"`) would match the first section of the first matching file in the XKB include paths, even if this section is not an *explicit* default map (i.e. tagged with `default`) but an *implicit* default map (i.e. the first map of the file, i.e. a weak match). It makes user configuration risky: say a user wants to create a custom version `au(custom)` of the `au` layout: - `./config/xkb/symbols/au`: custom layout in section “custom”. - `/usr/share/X11/xkb/symbols/au`: system layout, with *default* section “basic”. In this setup *any* layout that imports the default map from `au` would in fact import the *implicit* default map `au(custom)` instead of the *explicit* default map `au(basic)`. This incorrect behavior may thus break setups with multiple layouts. This is especially true for symbols files such as: `pc`, `us` or `latin`. Fixed by trying harder to found the exact default map, defaulting to the old behavior (weak match) only if no *explicit* default map (exact match) has been found in the XKB include paths.
Pierre Le Marre 00585c5c 2025-04-15T18:41:03 doc: Keymap format + misc
Pierre Le Marre 66f71890 2025-03-31T08:01:29 symbols: Enable writing keysyms list as UTF-8 strings Each Unicode code point of the string will be translated to their respective keysym, if possible. An empty string denotes `NoSymbol`. When such conversion is not possible, this will raise a syntax error. This introduces the following syntax: ```c // Empty string = `NoSymbol` key <1> {[""]}; // NoSymbol // Single code point = single keysym key <2> {["é"]}; // eacute // String = translate each code point to their respective keysym key <3> {["sßξك🎺"]}; // {s, ssharp, Greek_xi, Arabic_kaf, U1F3BA} // Mix string and keysyms key <4> {[{"ξ", Greek_kappa, "β"}]}; // { Greek_xi, Greek_kappa, Greek_beta} ``` It can also be used wherever a keysym is required, e.g. in `interpret` and `modifier_map` statements. In these cases a single keysym is expected, so the string should contain *exactly one* Unicode code point.
Pierre Le Marre 36442baa 2025-04-03T15:01:46 xkbcomp: Support multiple actions in interpret Before this commit we supported multiple actions per level, but not in *interpret* statements. Let’s fix this asymmetry, so we can equivalently assign all actions sets either implicitly or explicitly.
Pierre Le Marre 3d79f459 2025-03-29T11:46:34 xkbcomp: Add Unicode code point escape sequence \u{NNNN} Unicode code point escape sequences `\u{NNNN}` are replaced with the UTF-8 encoding of their corresponding code point `U+NNNN`, if legal. Supported Unicode code points are in the range `1‥0x10ffff`. Note that we will reject the `U+0000` NULL code point, as we reject it in the octal escape sequence `\0`. This is intended mainly for the upcoming feature to write keysyms as UTF-8 encoded strings. It can be used for various reasons: - avoid encoding issues; - avoid issue with font rendering (e.g. Asian scripts); - make white space or zero-width characters more readable.
Pierre Le Marre 23bbec96 2025-03-29T12:33:53 xkbcomp: Add escape sequence \" `\"` seems like a very natural extension. However it is not supported by Xorg xkbcomp, so do not emit it when serializing.
Pierre Le Marre 7d91a753 2025-03-29T12:24:39 xkbcomp: Enable xkbcomp-style octal escape sequences Xorg xkbcomp only parses octal sequences with `\0`, while xkbcommon does not force the `0` prefix of the numeric part. However, we only parsed up to to 3 digits, which does not allow to parse e.g. `\0377` while `\377` parses fine. Fixed by parsing up to 4 octal digits, while checking the result fits into a byte.
Pierre Le Marre 8594adc4 2025-03-31T13:52:36 doc: Mention that `alternate` merge mode is not supported
Pierre Le Marre 028869b1 2025-03-31T13:51:19 doc: Add sections for merge modes and include mechanism
Pierre Le Marre 44480f7c 2025-04-01T08:28:02 xkbcomp: Enable lists of keysyms and actions {} and {a} Motivations: - Follow the principle of least astonishment; - Ensure consistency; - Enhance the use of custom defaults; - Facilitate the tests. There is some ambiguity because we use `{}` to denote both an empty list of keysyms and an empty list of actions. But as soon as we get a keysym or an action, we know whether it is a `MultiKeySymList` or a `MultiActionList`. So we just count the `{}` at the *beginning* using `NoSymbolOrActionList`, then replace it by the relevant count of `NoSymbol` or `NoAction()` once the ambiguity is solved. If not, this is a list of empties of *some* type: we drop those empties and delegate the type resolution using `ExprEmptyList()`.
Pierre Le Marre 6881fb32 2025-04-01T08:28:02 xkbcomp: Drop trailing NoSymbol and NoAction() This brings us closer to what `xkbcomp` outputs. One should use the explicit `VoidSymbol` instead of `NoSymbol`, in order to avoid dropping empty levels. This may affect keys that rely on an *implicit* key type. Example: - Input: ```c key <> { [a, A, NoSymbol] }; ``` - Compilation with xkbcommon \< 1.9.0: ```c key <> { type= "FOUR_LEVEL_SEMIALPHABETIC", [a, A, NoSymbol, NoSymbol] }; ``` - Compilation with xkbcommon ≥ 1.9.0: ```c key <> { type= "ALPHABETIC", [a, A] }; ```
Pierre Le Marre 343c49cc 2025-03-30T09:54:02 doc: Optional components
Pierre Le Marre 23598fa1 2025-03-25T22:52:06 Enable merge mode “replace” in include statements Previously only the merge modes “override” and “augment” were available in include statements, using the prefix ‘+’ and ‘|’ respectively. While on one hand `replace` include statement can be used in keymap files, on the other hand *rules* files have no way to express the *replace* mode. This commit enables the merge mode “replace” using the prefix `^`. This prefix was chosen due to its similarity with the `XOR` bit operator, which convey *mutual exclusion*. Other candidates: - `!` conveys some kind of higher precedence, akin to CSS `!important`. But it conflicts with the section header `!`, which is a token in the current parser. It would require special handling, not worth it. It also convey the meaning of negation, which is confusing. - `&` has the advantage of not corresponding to a token in the rules parser. `^` seems however to stand out more and it is less likely to trigger erroneous comparison with `|` and `&` bit operators.
Pierre Le Marre 6fc6e64b 2025-03-26T10:35:22 rules: Added extended wild cards <none>, <some> and <any> Added the following wild cards to the rules file syntax, in addition to the current `*` legacy wild card: - `<none>`: Match *empty* value. - `<some>`: Match *non-empty* value. - `<any>`: Match *any* (optionally empty) value. Its behavior does not depend on the context, contrary to the legacy wild card `*`. This will enable writing much simpler rules, see [!764] for an example of tricky rules in the `xkeyboard-config` project, that would benefit from the new wild cards. [!764]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/merge_requests/764 The verbose wild cards are preferred to single characters: - More intuitive: self-explanatory. - Does not steal syntax from other token. - Extensible syntax, should we need it. A previous proposal used the characters (`!`, `+`, `?`) for their similarity with the corresponding syntax of regular expressions (negative assertion & quantifiers), in line with `*`. But `!` is not that intuitive after all and conflict with its role as section header. Furthermore, `+` is also used as a merge mode. Finally, nothing beats whole short words for readability.
Pierre Le Marre ecde6ade 2025-03-28T10:31:28 doc: Document floating-point parsing difference with Xorg xkbcomp
Pierre Le Marre f3a4eeaa 2025-03-26T16:04:39 symbols: Improve keysym parsing
Pierre Le Marre 70d11abd 2025-03-26T07:38:05 messages: Add file encoding and invalid syntax entries Added: - `XKB_ERROR_INVALID_FILE_ENCODING` - `XKB_ERROR_INVALID_RULES_SYNTAX` - `XKB_ERROR_INVALID_COMPOSE_SYNTAX` Changed: - `XKB_ERROR_INVALID_SYNTAX` renamed to `XKB_ERROR_INVALID_XKB_SYNTAX`.
Pierre Le Marre 04220319 2025-03-08T17:57:56 doc: Warn about the options order Options are always applied depending of their order in the relevant rules files, independently of their order in the relevant RMLVO config. Since this is counter-intuitive (e.g. when using `xkbcli`), let’s highlight this in the documentation.
Pierre Le Marre b2744402 2025-02-15T16:44:44 doc: Fix cool URIs
Pierre Le Marre b5cde5c1 2025-02-05T11:47:56 doc: Improve README
Pierre Le Marre a93fd7db 2025-02-05T11:43:37 doc: Fix Doxygen config - Use classical layout without a side bar, which is the default in recent Doxygen versions. - Use Github-style heading IDs: more user-friendly and stable. - Enable the Javascript-base search engine. - Generate `sitemaps.xml`. - Fix CSS width incompatible with small devices.
Pierre Le Marre c85c9bdc 2025-01-27T17:15:06 symbols: Allow levels with different keysyms and actions counts Contrary to groups, there is no reason for levels to restrict the same count of keysyms and actions.
Pierre Le Marre 27ac30b2 2025-01-27T17:13:44 symbols: Normalize levels by dropping NoSymbol & NoAction
Pierre Le Marre d2eb8601 2025-01-07T08:00:06 doc: Mark $HOME/.xkb/ as a deprecated location for user configuration `$HOME/.xkb` was supported before the addition of the XDG directories. Removal of the functionality is just going to cause potential breakage for now good technical reason. See https://specifications.freedesktop.org/basedir-spec/latest/ for further details.
Pierre Le Marre 16eff222 2024-12-31T08:01:52 doc: Add debugging page and warning about session restart Co-authored-by: Pierre Le Marre <dev@wismill.eu> Co-authored-by: Peter Hutterer <peter.hutterer@who-t.net>
Pierre Le Marre b1da948a 2024-10-08T19:43:18 symbols: Add doc for multiple actions
Pierre Le Marre 60228356 2024-10-07T10:42:27 symbols: Add message ID for incompatible keysyms and actions counts
Pierre Le Marre 4ea9d431 2023-11-16T17:12:03 rules: Add support for :all qualifier Some layout options require to be applied to every group to maintain consistency (e.g. a group switcher). Currently this must be done manually for all layout indexes. This is error prone and prevents the increase of the maximum group count. This commit introduces the `:all` qualifier for KcCGST values. When a rule with this qualifier is matched, it will expands the qualified value (and its optional merge mode) for every layout, e.g. `+group(toggle):all` (respectively `|group(toggle)`) would expand to `+group(toggle):1+group(toggle):2` (respectively `|group(toggle):1|group(toggle):2`) if there are 2 layouts, etc. If there is no merge mode, it defaults to *override* `+`, e.g. `x:all` expands to `x:1+x:2+x:3` for 3 layouts. Note that only the qualified *value* is expanded, e.g. `x+y:all` expands to `x+y:1+y:2` for 2 layouts. `:all` can be used in combination with special layout indexes. Since this can lead to an unexpected behaviour, a warning will be raised.
Pierre Le Marre cdafba4f 2024-09-24T15:23:16 rules: Add support for index ranges There is a lot of repetition in the current rules files provided by xkeyboard-config, because the MLVO mappings need to match on the exact layout/variant index. This also prevents to increase the number of maximum groups, because it does not scale. We introduces the following new special layout/variant indexes: - “single”: matches a single layout; same as with no index. - “first”: matches the first layout/variant, no matter how many layouts are in the RMLVO configuration. It allows to merge `layout` and `layout[1]` patterns. - “later”: matches all but the first layout. This is an index range. - “any”: matches layout at any position. This is an index range. We also introduces the new `%i` expansion, which correspond to the index of the matched layout in a mapping with an index range. Example: layout[later] = symbols my_layout = +my_symbols:%i * = +%l[%i]:%i Let’s have a look at concrete examples from xkeyboard-config: ! model layout = symbols * * = pc+%l%(v) ! model layout[1] = symbols * * = pc+%l[1]%(v[1]) ! model layout[2] = symbols * * = +%l[2]%(v[2]) ! model layout[3] = symbols * * = +%l[3]%(v[3]) ! model layout[4] = symbols * * = +%l[4]%(v[4]) ! layout option = symbols * grp:toggle = +group(toggle) ! layout[1] option = symbols * grp:toggle = +group(toggle):1 ! layout[2] option = symbols * grp:toggle = +group(toggle):2 ! layout[3] option = symbols * grp:toggle = +group(toggle):3 ! layout[4] option = symbols * grp:toggle = +group(toggle):4 With this commit we can now simplify it into: ! model layout[first] = symbols * * = pc+%l[%i]%(v[%i]) ! model layout[later] = symbols * * = +%l[%i]%(v[%i]):%i ! layout[any] option = symbols * grp:toggle = +group(toggle):%i The latter rule will work even if we increase XKB_MAX_GROUPS, whereas the former would require to add the missing entries for the new groups. In order to maintain consistent rules, we now disallow layout and variant to have different indexes. For example, the following mapping are now invalid: - layout variant[1] - layout[1] variant[2] - layout[1] variant - layout[first] variant[1] - layout[first] variant - layout variant[any] - etc.
Pierre Le Marre a898bc81 2024-09-25T06:47:23 logging: Added new error messages ID for keymap and rules
Pierre Le Marre 1b83771f 2024-09-24T22:48:01 logging: Use messages ID in registry
Pierre Le Marre 7697c712 2024-09-16T16:09:11 rules: Resolve relative include statements using XKB paths Contrary to keymap files, the `! include` statement in rules does not lookup include paths added to `xkb_context`. So it is not possible e.g. to import another file in the same folder without using an absolute path. - Added path utils: `is_absolute(path)`. - Added XKB paths lookup to enable e.g. `! include evdev` to work. - Added test.
Pierre Le Marre 44df6eee 2024-09-23T07:27:48 Add new warnings for deprecated keysyms Add 2 new warnings: - Deprecated keysym name (typo, historical alias, etc.); - Deprecated keysym (all names and forms). Guard deprecated keysym tests with verbosity level ≥2, so they are run only when actually needed.
Pierre Le Marre 05ba96db 2024-08-20T16:41:38 rules: Fix wild card handling The handling of wild card `*` is different in libxkbfile and X server: wild card matches empty strings for model and option but not for layout nor variant, while in libxkbcommon wild cards always match empty strings. See: - https://gitlab.freedesktop.org/xorg/lib/libxkbfile/-/blob/bf985c68acb1244f51ec91414532a2347fbc1c4c/src/maprules.c#L687 - https://gitlab.freedesktop.org/xorg/lib/libxkbfile/-/blob/bf985c68acb1244f51ec91414532a2347fbc1c4c/src/maprules.c#L712 The difference of handling between the components is unfortunately not documented, but we should follow the behavior of the original implementations for consistency. - Fixed by implementing the same behavior than libxkbfile. - Added tests and fixed failing tests. - Improve the documentation of rules to highlight the special behavior.
Pierre Le Marre 32179d91 2024-03-01T08:44:35 doc: Improve rules - Improved introduction - Added examples - Added RMLVO resolution process
Pierre Le Marre e4b20b91 2024-03-15T18:57:32 doc(keymap): Improve types & symbols sections - Add a diagram to illustrate how key types work. - Add examples to explain the key types mappings. - Add note for using `preserve` to tweak shortcuts. - Improve the key statement section.
Pierre Le Marre a4946488 2024-03-15T17:16:13 doc(keymap): Fix quotes and apostrophe Straight apostrophe `'` and straight quotations marks `"` are typewriter legacy and should only be used in programming. apostrophe
Pierre Le Marre 13b36a76 2024-03-01T15:02:41 Global default statement: Improve code & error message - Simplify error handling. - Improve error message: add message ID and relevant quotes and try to standardize a bit. - Add proper doc for in the message registry. Note: Instead of testing the value of `expr.op`, we test if the argument `elem` of `ExprResolveLhs` is set: this allows us to catch also the error with `x.y[z]` rather than just `x.y` as previously.
Pierre Le Marre 64614bcc 2024-03-01T15:02:41 doc: Fix message entries count It seems an error originating from 00e3058e7b027c3d698b24415fd2ac105cd72246A. Probably an unfortunate Git rebase or so.
Pierre Le Marre 2c23852a 2024-02-29T18:16:54 Doc: Keymap format enhancement + misc - Add introduction to keymap and its components - Add a diagram to explain the relationships between RMLVO and KcCGST. - Add keywords & comments sections. - Improve Quick guide section in the index page. - Add links to User-configuration page. - Fix typos.
Peter Hutterer 54f073ce 2024-02-05T11:11:11 doc: remove obsolete HTML_TIMESTAMP warning: Tag 'HTML_TIMESTAMP' at line 44 of file '/home/whot/xorg/lib/libxkbcommon/build/Doxyfile' has become obsolete.
Peter Hutterer 31ebe003 2023-12-19T09:15:14 test: add a test for multiple keysyms (and some minimal docs) I couldn't find any reference to *how* the keymap format actually needs to look like if you want multiple keysyms per level. So let's add a test for it and a minimal documentation entry.
Pierre Le Marre 79502700 2023-11-14T10:10:50 Doc: fix malformed links and some typos
Pierre Le Marre 00e3058e 2023-11-06T21:53:51 Prevent recursive includes of keymap components - Add check for recursive includes of keymap components. It relies on limiting the include depth. The threshold is currently to 15, which seems reasonable with plenty of margin for keymaps in the wild. - Add corresponding new log message `recursive-include`. - Add tests for recursive includes.
Pierre Le Marre 171e0170 2023-10-25T20:39:39 Fix memory leak in FindFileInXkbPath The string `buf` was not freed after each call to `asprintf_safe`. Avoid allocating and introduce the new message: `XKB_ERROR_INSUFFICIENT_BUFFER_SIZE`.
Pierre Le Marre ca7aa69c 2023-09-26T17:05:05 Disallow producing NULL character with escape sequences NULL usually terminates the strings; allowing to produce it via escape sequences may lead to undefined behaviour. - Make NULL escape sequences (e.g. `\0` and `\x0`) invalid. - Add corresponding test. - Introduce the new message: XKB_WARNING_INVALID_ESCAPE_SEQUENCE.
Pierre Le Marre a83d745b 2023-09-21T20:06:27 Messages: add new messages to registry This commit is another step to identify and document the maximum number of logging messages. Bulk changes: - Rename `conflicting-key-type` to `conflicting-key-type-merging-groups`. Giving more context in the name allow us to introduce `conflicting-key-type-definitions` later. - Add conflicting-key-type-definitions - Add conflicting-key-type-map-entry - Add undeclared-modifiers-in-key-type Also improve the log messages. - Add conflicting-key-type-preserve-entries - Use XKB_ERROR_UNSUPPORTED_MODIFIER_MASK - Add illegal-key-type-preserve-result - Add conflicting-key-type-level-names - Add duplicate-entry - Add unsupported-symbols-field - Add missing-symbols-group-name-index - Use XKB_ERROR_WRONG_FIELD_TYPE - Add conflicting-key-name - Use XKB_WARNING_UNDEFINED_KEYCODE - Add illegal-keycode-alias - Add unsupported-geometry-section - Add missing-default-section - Add XKB_LOG_MESSAGE_NO_ID - Rename log_vrb_with_code to log_vrb - Use ERROR_WRONG_FIELD_TYPE & ERROR_INVALID_SYNTAX - Add unknown-identifier - Add invalid-expression-type - Add invalid-operation + fixes - Add unknown-operator - Rename ERROR_UNKNOWN_IDENTIFIER to ERROR_INVALID_IDENTIFIER - Add undeclared-virtual-modifier - Add expected-array-entry - Add invalid-include-statement - Add included-file-not-found - Add allocation-error - Add invalid-included-file - Process symbols.c - Add invalid-value - Add invalid-real-modifier - Add unknown-field - Add wrong-scope - Add invalid-modmap-entry - Add wrong-statement-type - Add conflicting-key-symbols-entry - Add invalid-set-default-statement
Pierre Le Marre eafd3ace 2023-09-18T18:17:39 Add a new warning for numeric keysyms Usually it is better to use the corresponding human-friendly keysym names. If there is none, then the keysym is most probably not supported in the ecosystem. The only use case I see is similar to the PUA in Unicode (see: https://en.wikipedia.org/wiki/Private_Use_Areas). I am not aware of examples of this kind of use.
Pierre Le Marre ef81d04e 2023-09-18T18:17:34 Structured log messages with a message registry Currently there is little structure in the log messages, making difficult to use them for the following use cases: - A user looking for help about a log message: the user probably uses a search engine, thus the results will depend on the proper indexing of our documentation and the various forums. It relies only on the wording of the message, which may change with time. - A user wants to filter the logs resulting of the use of one of the components of xkbcommon. A typical example would be testing xkeyboard-config against libxkbcommon. It requires the use of a pattern (simple words detection or regex). The issue is that the pattern may become silently out-of-sync with xkbcommon. A common practice (e.g. in compilers) is to assign unique error codes to reference theses messages, along with an error index for documentation. Thus this commit implements the following features: - Create a message registry (message-registry.yaml) that defines the log messages produced by xkbcommon. This is a simple YAML file that provides, for each message: - A unique numeric code as a short identifier. It is used in the output message and thus can be easily be filtered to spot errors or searched in the internet. It must not change: if the semantics of message changes, it is better to introduce a new message for clarity. - A unique text identifier, meant for two uses: 1. Generate constants dealing with log information in our code base. 2. Generate human-friendly names for the documentation. - A type: currently warning or error. Used to prefix the constants (see hereinabove) and for basic classification in documentation. - A short description, used as concise and mandatory documentation. - An optionnal detailed description. - Optional examples, intended to help the user to fix issues themself. - Version of xkbcommon it was added. For old entries this often unknown, so they will default to 1.0.0. - Version of xkbcommon it was removed (optional) No entry should ever be deleted from this index, even if the message is not used anymore: it ensures we have unique identifiers along the history of xkbcommon, and that users can refer to the documentation even for older versions. - Add the script update-message-registry.py to generate the following files: - messages.h: message code enumeration for the messages currently used in the code base. Currently a private API. - message.registry.md: the error index documentation page. - Modify the logging functions to use structured messages. This is a work in progress.
Ran Benita c1b6c79a 2023-07-31T22:35:16 doc: fix some Doxygen warnings ``` libxkbcommon/doc/introduction-to-xkb.md:67: warning: unable to resolve reference to 'rule-file-format' for \ref command libxkbcommon/doc/introduction-to-xkb.md:181: warning: unable to resolve reference to 'keymap-text-format-v1' for \ref command libxkbcommon/doc/rules-format.md:10: warning: unable to resolve reference to 'xkb-intro' for \ref command ``` Signed-off-by: Ran Benita <ran@unusedvar.com>
Wismill 64aaa7cd 2023-05-14T15:11:15 Add support for stable doc URLs (#342) Doc URLs may change with time because they depend on Doxygen machinery. This is unfortunate because it is good practice to keep valid URLs (see: https://www.w3.org/Provider/Style/URI.html). I could not find a built-in solution in Doxygen, so the solution proposed here is to maintain a registry of all URLs and manage legacy URLs as redirections to their canonical page. This commit adds a registry of URLs that has three functions: - Check no previous URL is now invalid. - Add aliases for moved pages. - Generate redirection pages for aliases. The redirection works with a simple <meta http-equiv="refresh"> HTML tag. See: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#http-equiv This commit also initialize the URLs registry with current pages and some redirections needed after recent documentation refactoring. Finally, the CI is updated to catch any change that invalidate previous URLs.
Pierre Le Marre fc664cf1 2023-05-13T05:30:11 Improve documentation - Add introduction to XKB - Embrace Doxygen features - More cross links
Ran Benita e4226011 2023-05-04T11:55:51 Use consistent indentation for map and CSS files Signed-off-by: Ran Benita <ran@unusedvar.com>
Wismill 0e9c2ec9 2023-04-30T21:30:36 Improve the doc of the XKB keymap text format, V1 (#321) - Add table of contents - Add terminology section - (WIP) Add Introduction to the format - Improve the keycode section - Improve the interpret section - Add guide to create and use modifiers - (WIP) Add actions documentation - Add cross-references - Add keysyms header to documentation
Ran Benita 09ac27f7 2021-05-22T19:51:02 ignore: remove no longer relevant gitignore files These were relevant for the autoconf build but now we're meson only. Signed-off-by: Ran Benita <ran@unusedvar.com>
Jouke Witteveen 8b603dbe 2021-04-10T23:28:06 doc: fix user-configuration sample file Support copy-pasting from the docs to get something functional. Signed-off-by: Jouke Witteveen <j.witteveen@gmail.com>
Ran Benita 83e3a53d 2021-02-27T22:38:21 doc: add keymap-format-text-v1.md to the HTML documentation It's incomplete but might be helpful for someone. Signed-off-by: Ran Benita <ran@unusedvar.com>
Ran Benita 44df69c9 2020-12-27T09:47:08 doc/keymap: some slight editing Signed-off-by: Ran Benita <ran@unusedvar.com>
Simon Zeni 7420521f 2020-12-27T02:48:39 doc/keymap: add documentation for xkb_symbols (#205)
Peter Hutterer ae90a6a0 2020-08-26T15:47:51 doc: add some disclaimer regarding user-specific key types and compat entries It's a niche use-case but basically the same as adding symbols, so let's go with a general handwavy explanation. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Peter Hutterer d7b39f6f 2020-07-10T08:50:02 Add /etc/xkb as extra lookup path for system data files This completes the usual triplet of configuration locations available for most processes: - vendor-provided data files in /usr/share/X11/xkb - system-specific data files in /etc/xkb - user-specific data files in $XDG_CONFIG_HOME/xkb The default lookup order user, system, vendor, just like everything else that uses these conventions. For include directives in rules files, the '%E' resolves to that path. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Ran Benita 81842f7f 2020-07-25T17:18:02 doc: ignore rxkb, RXBK prefixes in doxygen Signed-off-by: Ran Benita <ran@unusedvar.com>
Peter Hutterer afb26e7d 2020-05-12T14:09:50 Add libxkbregistry to query available RMLVO This library is the replacement for clients parsing evdev.xml directly. Instead, they should use the API here so that in the future we may even be able to swap evdev.xml for a more suitable data format. The library parses through evdev.xml (using libxml2) and - if requested - through evdev.extras.xml as well. The merge approach is optimised for the default case where we have a system-installed rules XML and another file in $XDG_CONFIG_DIR that adds a few entries. We load the system file first, then append any custom ones to that. It's not possible to overwrite the MLVO list provided by the system files - if you want to do that, get the change upstream. XML validation is handled through the DTD itself which means we only need to check for a nonempty name, everything else the DTD validation should complain about. The logging system is effectively identical to xkbcommon. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Peter Hutterer 3adbe54e 2020-06-23T16:20:08 tools: move the remaining tools from test to here Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Peter Hutterer 4e544e27 2020-06-16T10:44:48 doc: correct the include path list XKB_CONFIG_ROOT (if defined) replaces the built-in system directories. Fixes 5fb2c6769b7259ba647781bc800d6a46d90cf1a9 Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Peter Hutterer 5fb2c676 2020-06-02T16:18:47 doc: add documentation for user configuration Most of this is currently hidden in the commit message for ca033a29d2ca, let's make it a bit more public so we have a link to point users to. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Peter Hutterer a2657874 2020-06-02T16:11:33 doc: add the rules-format file (as markdown) Useful to have this as part of the documentation. The rendering isn't great but at least not any worse than pure text. Markdown escapes % so explaining our use of %S and %H would require a double % - not idea. Let's just wrap it as a code block and done. Includes two typo fixes too, yay. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Ran Benita 517464eb 2020-01-18T23:06:58 doc/rules-format.txt: document include support Signed-off-by: Ran Benita <ran@unusedvar.com>
Ran Benita 41bea9ab 2017-08-01T22:19:48 build: make doxygen run from the source tree I couldn't find any other way to make this work! Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 4983dbcf 2017-07-28T18:19:40 build: change doxygen target to be properly dependency-based This hackery (thanks libinput) is clearer and more precise than the previous hackery. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 148aec8b 2017-04-29T15:26:38 doc/compat: correct the XKB protocol version from 1.1 to 1.0 There is no XKB 1.1! Thanks to Oded Arbel for catching this. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 599fd9ba 2016-09-01T21:17:43 doc/compat: (! MODIFIER) syntax is parsed but ignored Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita c29afcc3 2016-09-01T21:13:49 doc/compat.md: xkbcomp ignores multiple-keysyms these days https://cgit.freedesktop.org/xorg/app/xkbcomp/commit/?id=e119cbec7e750ffc4d4bd08b577db2c697035a30 Signed-off-by: Ran Benita <ran234@gmail.com>
Bryce Harrington d58fc90a 2016-06-15T17:36:18 doc: Also mention the wayland test client in the quick guide Signed-off-by: Bryce Harrington <bryce@osg.samsung.com>
Bryce Harrington 094c8dc5 2016-06-15T17:36:17 doc: Declare keymap for wayland example keymap was defined in the X11 example, but also define it in the wayland example just to make it a bit more standalone Signed-off-by: Bryce Harrington <bryce@osg.samsung.com>
Bryce Harrington 832e32dc 2016-06-15T17:36:16 doc: Fix ctx type in example xkb_context_new() returns a xkb_context pointer, so change the variable definition to be consistent. Signed-off-by: Bryce Harrington <bryce@osg.samsung.com>
kmx.io     mail     discord kmxgit v0.4.0