The handling of keysym name guards (e.g. `#ifndef XK_Ydiaeresis`) was
incomplete and led to a missing keysym.
Make `sripts/makeheader` more robust to C macros handling.
- Add bash completion script. It parses the commands help messages to
provide the completions, thus any new subcommand or option will be
supported, as long as it has its entry in the help messages. This
should result in low maintenancei effort.
- Add installation entry in Meson. The path can be configured using
the following options:
- `enable-bash-completion` to enable the installation;
- `bash-completion-path` to control the installation path. It will
default to: `share/bash-completion/completions`.
TODO: completion for other shells, such as zsh?
See https://pre-commit.com for further info. Current checks:
- Whitespaces
- Yaml
- Large files
- Python linting/formatting
TODO: investigate options for C linter and formatter
- Update keymap to use reference keysym names.
- Fix x11comp test by handling old x11proto.
We need xkbcomp to be compiled with at least x11proto-dev 2023.2.
So we replace the unsupported keysyms with supported ones not
already in the keymap. This is kind of ugly, but it works. If we
ever want to restore the original keysyms with their supported names,
the substitute keysyms will be easy to spot.
The octal parser accepts the range `\1..\777`. The result is cast to
`char` which will silently overflow.
This commit prevents overlow and will treat `\400..\777` as invalid
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.
Allow users to iterate the entries in a compose table. This is useful
for other projects which want programmable access to the sequences,
without having to write their own parser.
- New API:
- `xkb_compose_table_entry_sequence`;
- `xkb_compose_table_entry_keysym`;
- `xkb_compose_table_entry_utf8`;
- `xkb_compose_table_iterator_new`;
- `xkb_compose_table_iterator_free`;
- `xkb_compose_table_iterator_next`.
- Add tests in `test/compose.c`.
- Add benchmark for compose traversal.
- `tools/compose.c`:
- Print entries instead of just validating them.
- Add `--file` option.
- TODO: make this tool part of the xkbcli commands.
Co-authored-by: Pierre Le Marre <dev@wismill.eu>
Co-authored-by: Ran Benita <ran@unusedvar.com>
Signed-off-by: Ran Benita <ran@unusedvar.com>
Previously we had two types of macros for logging: with and without
message code. They were intended to be merged afterwards.
The idea is to use a special code – `XKB_LOG_MESSAGE_NO_ID = 0` – that
should *not* be displayed. But we would like to avoid checking this
special code at run time. This is achieved using macro tricks; they
are detailed in the code (see: `PREPEND_MESSAGE_ID`).
Now it is also easier to spot the remaining undocumented log entries:
just search `XKB_LOG_MESSAGE_NO_ID`.
Motivation: normalization of keysyms header files in `xorgproto`. See:
https://gitlab.freedesktop.org/xorg/proto/xorgproto/-/merge_requests/80
Improve `scripts/makeheader`:
- Simplify `evdev` and `XK_` substitution and improve alignment. Also, perform
some additional `XK_` substitutions in comments.
- Format with `black`.
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.
This tool checks whether messages codes are supported.
This is useful e.g. for CI, where one may want to grep for some XKB
error codes and ensure that these are still supported.
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.
Add an option to print modmap and vmodmap of relevant keys, as well as
virtual modifiers mapping to real modifier. This is useful for debugging.
It uses private API, so we compile it separately in the fashion of
`xkbcli-compile-keymap/compile-keymap`.
Currently the interactive tools print the string result of key strokes
as it is, without any escape. This is especially annoying for trivial
keysyms such as: Return, BackSpace and Escape.
Fix this by displaying the Unicode code point notation (e.g U+000D for
Return) for single control characters from the C0 set and DEL.
This is a hack: ideally we would like to escape any non-printable
character in the utf-8 string.
Based on the work done by Peter Hutterer. Original commit message:
If SIGUSR1 is set to SIG_IGN, X servers (all of them, including Xvfb)
will send that signal to the parent process when they're ready to accept
connections. We can use that instead of a hardcoded sleep which brings
the wait down to ~37ms on my box.
The x11 test is currently silently skipped in CI, because it requires a
running X server.
Create a xvfb wrapper to run the test. We do not use `xvfb-run`, because
it is a shell script and it causes valgrind to detect unrelated memory
issues in the shell (dash, bash).
Improve wrapper using a special ELF section
TODO: The wrapper is intended to be used with the x11comp test as well.
```
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>
- Add a keymap test with decimal and hexadecimal keysyms.
- Reorganize code in `test/keysym.c` by parsing type: name, Unicode and
hexadecimal.
- Add more tests for edge cases. In particular:
- test decimal format (currently not supported);
- test the Unicode and hexadecimal ranges more thoroughly;
- test with wrong case without the XKB_KEYSYM_CASE_INSENSITIVE flag;
- test surrounding spaces.
- Document the tests.
In `parser.y`, a numeric keysym is parsed by formatting it in its
hexadecimal form then parsed as a keysym name. This is convoluted.
Fixed by checking directly the upper bound.
When parsing hexadecimal keysym using `xkb_keysym_from_name`,
the result is limited by `parse_keysym_hex` to 0xffffffff, but the
maximum keysym is XKB_MAX_KEYSYM, i.e. 0x1fffffff.
Fixed by adding an upper bound.
Keysyms are 32-bit integers with the 3 most significant bits always set
to zero. See: Appendix A “KEYSYM Encoding” of the X Window System
Protocol at https://www.x.org/releases/current/doc/xproto/x11protocol.html#keysym_encoding.
Add a new constants XKB_KEYSYM_MIN and XKB_KEYSYM_MAX to make the
interval of valid keysyms more obvious in the code.
Doxygen 1.9.7 breaks our urls, see issue #347. Let's put a check for the
doxygen version into our CI build so that if our base distro updates beyond
that, the CI fails and we know we have to build doxygen from scratch or
update to some other version that's supported.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Upload the doxygen output as artifact from the linux build and use that from
the pages job where we combine the static website with our newly build HTML
docs. The GitHub actions/download-artefact doesn't work across workflows so
we use the other popular one that can do this. The rest of the job is
basically copy/paste from the "Static HTML" example GitHub provides.
To make this useful as drop-in replacement, replace the one fixed link to the
API docs a relative one.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
The script `ensure-stable-doc-urls.py` relies on the Doxygen output files
names. These may change between Doxygen versions, although the Doxygen
developers intend stability.
Since the script is useful mainly for the online documentation of
xkbcommon, make the target `doc-cool-uris` optional.
The test `test_from_locale` fails when there is a user-defined compose
file, e.g. ~/.XCompose.
Indeed, the function `xkb_compose_table_new_from_locale` use various
environment variables to determine the location of the compose file.
Ensure no environment variables but the required ones are set, in order
to have robust tests.
Currently there is no interactive tool allowing to set the include
paths of the context, such as in "compile-keymap". Note that only
"interactive-evdev" makes sense, because it does not rely on a
compositor.
Add --include and --include-defaults to "interactive-evdev" tool.
The code is adapted from "compile-keymap".
- Force Doxygen version 1.9.6, because 1.9.7 breaks our doc cool URIs,
i.e. our system that maintain stable doc pages via redirection.
Associated issue in Doxygen:
https://github.com/doxygen/doxygen/issues/10146
- Install graphviz to build the .dot files.
In commit 1638409b22, the number of
compose nodes was limited to 65535 to enable "future optimizations",
which apparently means slightly reduced memory usage due to fitting in
a uint16_t. At this time, it was mentioned that the author was not
aware of "any compose files which come close".
However, I'm one of the users that actually do require a larger number
of nodes for their compose file. Thus, use a uint32_t again and raise
the limit significantly.
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
Ran Benita
M Kelly
Peter Hutterer
alois31