Better documentation for .XCompose support
GTK has an ImContextSimple input method whose only special behaviors are Ctrl-U + Unicode code point, and compose key support.
On the other hand, GNOME by default uses the IBus input method (IBus is required in GNOME Shell, which has GUI controls for IBus). Now, IBus has its own compose support. I've witnessed behavior differences between IBus and GTK, the latter tested by running apps from a terminal with GTK_IM_MODULE=gtk-im-context-simple
. For example, with include
directives and default compose sequences.
Currently, documentation about compose support is scarce. I have found nothing on https://help.gnome.org/users/. There is however https://help.gnome.org/admin/system-admin-guide/stable/keyboard-compose-key.html.en, which is in the "System Administration Guide" section (why?), and shows steps to enable the compose key via config files; this looks obsolete, since there is now a GUI selector to enable it in the GNOME Settings app.
There is a short section in the GNOME Help app, in Tips & tricks > Enter special characters > Compose key. It mostly explains how to enable the key in GNOME Settings.
The last piece of GNOME documentation I know that mentions compose keys is https://docs.gtk.org/gtk4/class.IMContextSimple.html, which is GTK API documentation, not user-oriented documentation, and (understandably given its purpose as API documentation of ImContextSimple
) it doesn't mention at all that for most users, its description of .XCompose quirks doesn't apply because IBus is being used.
(IBus is also very lacking from the documentation point of view, but that's not an issue for this project. Also, none of this is made easier by the fact that a lot of the information you can find on the Web, such as on the ArchLinux and Ubuntu wikis, is out-of-date due to the Xorg → Wayland switch and other changes. What I understand is partly figured out by reading GTK and IBus source code plus old threads on the GNOME developer mailing list at the time of the IBus integration in ~2012.)
I would like to see documentation for these points:
-
Some general page on the compose key, mentioning that you can define your own sequences in a .XCompose file, with the caveat that GTK without IBus, Qt without IBus and IBus may have interpretation differences.
-
Where default compose sequences are to be found. The GNOME help center points to https://en.wikipedia.org/wiki/Compose_key#Common_compose_combinations, which only shows a few common ones. That Wikipedia page does have a link to some Xorg source file in a footnote. It looks like IBus and GTK use that file, although it is worth noting that this is only Xorg's compose sequences for the English locale; compose sequences are locale-dependent in Xorg and locale-independent in GTK; I don't fully understand where IBus reads compose files yet but it's definitely locale-dependent too.
-
How to reload the compose file without logging out and in:
ibus restart
, when IBus is being used. I don't think there's a way withIMContextSimple
, is that correct? -
Why GTK provides
IMContextSimple
at all. This is for the IMContextSimple documentation. Basically, in which cases is it useful for developers to set this input method on their widgets instead of the default? Or is it not meant to be set on individual widgets but just used as a global default by a system? I don't quite understand what it's for, now that GNOME uses IBus by default. Is it useful on systems with neither IBus nor Fcitx5 or some other input method that supports compose keys? Which systems? On macOS and Windows, the few users using a compose key should be doing it via apps that hook into the system-native input methods (which GTK knows how to use). Is it for minimalistic desktop environments that don't support input methods? For Linux-from-scratch-type people? Or for BSDs or something?
I have a related question, admittedly deviating a bit from the topic of documentation, but since my post on discourse.gnome.org had no reply, allow me to raise it here: assuming that IMContextSimple
is useful, why does GTK have its own .XCompose parser? It depends on libxkbcommon, which has a .XCompose parsing API. (So, yes, that makes 3 different .XCompose parsers in the stack, between libxkbcommon, GTK and IBus. The GTK and IBus ones look like they share a common origin, as there are character-identical functions between the two. There's one in in Qt and one in ibus-typing-booster as well… This wouldn't be a problem if the format was trivial, but the handling of includes for example is inconsistent.)
I'm willing to provide doc patches, whether here or wherever the sources of https://help.gnome.org/ and the GNOME Help app are, but I need to understand the situation first. Thanks.