Hojun-Cho
ef7fb627c6
An IBus client throws away a dead key its engine did not take — the GTK module's own comment says so, and Qt does the same — so é and ü were lost in every IBus application, while XIM composed them with a table of its own. That table moves to compose.c, which both frontends now use; xim.c is the shorter for it. A finished sequence is text, not a key: the engine is asked to hand back what it had pending, and the composed text follows it, so the composed character can no longer land before the syllable typed before it.
231 lines
9.1 KiB
Markdown
231 lines
9.1 KiB
Markdown
# strans
|
|
|
|
strans is a small, single-user input method for Korean, Japanese, English,
|
|
emoji, and symbols. It provides one engine for IBus (which GTK 4 and
|
|
Qt use), XIM, and GTK 3. Vietnamese Telex is also available as a
|
|
compatibility mode.
|
|
|
|
## Input modes
|
|
|
|
| Key | Mode |
|
|
| --- | --- |
|
|
| `Ctrl+N` | Japanese Hiragana and Kanji conversion |
|
|
| `Ctrl+K` | Japanese Katakana |
|
|
| `Ctrl+S` | Korean Hangul (2-beolsik) |
|
|
| `Ctrl+T` | English |
|
|
| `Ctrl+V` | Vietnamese Telex |
|
|
| `Ctrl+E` | Emoji and symbol search |
|
|
| `Ctrl+H` | One-shot Hanja search |
|
|
|
|
A Korean keyboard's 한/영 key toggles Korean and English, and its 한자 key
|
|
is `Ctrl+H`; a Japanese keyboard's 半角/全角 toggles Japanese and English,
|
|
ひらがな/カタカナ switches between the two kana modes, 変換 turns Japanese
|
|
on and then converts like `Space`, and 無変換 turns it off. Only a plain
|
|
`Ctrl` chord is a strans key: with `Shift`, `Alt`, or `Super` held it
|
|
commits what is pending and goes to the application, so `Ctrl+Shift+V`
|
|
still pastes.
|
|
|
|
Hiragana mode composes a complete reading, then shows its Kanji candidates
|
|
with none chosen: the exact readings of the dictionary, then the verbs and
|
|
adjectives SKK keys by stem and okurigana (かく offers 確 and 書く), and
|
|
under `Space` the reading in Katakana last, so a word the dictionary lacks
|
|
converts to Katakana with one `Space`. `Space` or `Tab` chooses the first
|
|
candidate and then steps on, wrapping (with `Shift`, back); `Up`/`Down` and
|
|
`PageUp`/`PageDown` move without wrapping. An unmodified `1`-`9` commits
|
|
that row of the current page. `Enter` commits the chosen candidate, or the
|
|
reading when none is chosen, as `0` always does; so does typing on, or any
|
|
key that ends the composition. `Backspace` deletes the last kana shown;
|
|
romaji that made no kana stays in the reading as typed until it is mended.
|
|
`Backspace` and `Esc` on a chosen candidate go back to the reading, and
|
|
`Esc` on the reading cancels it. Katakana mode does not perform Kanji
|
|
conversion.
|
|
|
|
Korean composes one syllable at a time; `Enter`, `Tab`, `Esc`, and any key
|
|
that is not a jamo commit the syllable and go on to the application, so
|
|
`Esc` still leaves insert mode. Two lone consonants join into the compound
|
|
final they make (rt → ㄳ) and a vowel typed before its consonant is
|
|
reordered under it (kr → 가), as in libhangul.
|
|
|
|
Emoji and Hanja searches take over the keys until `Enter`, `Space`, or a
|
|
digit picks a result or `Esc` cancels; they return to the previous mode
|
|
after use, and switching language during a search commits the shown
|
|
query. `Tab`/`Shift-Tab` wrap through the results, and a search with
|
|
nothing typed yet shows ☺ or 漢 in the popup. The Emoji search matches the
|
|
typed keys, and what they spell in the current language, against a prefix
|
|
of every emoji's CLDR name and keywords in English, Korean, and Japanese,
|
|
and against ASCII symbol aliases such as `->` and `<=`. `Ctrl+H` takes the
|
|
syllable being composed as its query and composes on from it; `Esc` gives
|
|
the syllable back; the Hanja dictionary lists one modern Hangul syllable at
|
|
a time. Leaving the field or clicking elsewhere commits what is pending.
|
|
|
|
## Preedit and candidates
|
|
|
|
| Frontend | Preedit | Candidates |
|
|
| --- | --- | --- |
|
|
| GTK 3 and IBus | inline in the client | strans popup |
|
|
| XIM PreeditCallbacks | inline through XIM callbacks | strans popup |
|
|
| XIM PreeditPosition | strans popup | strans popup |
|
|
| XIM PreeditNothing | strans popup | strans popup |
|
|
|
|
Each XIM style is offered with StatusNothing and with StatusNone.
|
|
|
|
Dead keys and Compose sequences are composed by strans itself for the XIM
|
|
and IBus frontends, from the table `XCOMPOSEFILE` or the locale names; the
|
|
GTK 3 module leaves them to GtkIMContextSimple. Their text follows
|
|
whatever was pending.
|
|
|
|
XIM text travels as `COMPOUND_TEXT`, which carries any UTF-8. A client that
|
|
sends `XNSpotLocation` gets the popup under that spot whatever its preedit
|
|
style, and above the line when there is no room below; otherwise the popup
|
|
sits under the focus window, or under the client window when no focus
|
|
window is set.
|
|
|
|
The popup is an X11 window sized by `GDK_SCALE` on HiDPI displays, XIM is
|
|
X11-only, and GTK popup placement converts the GTK caret to X11 root
|
|
coordinates. There is no native Wayland popup surface or Wayland caret
|
|
positioning. GTK and IBus clients can still use inline preedit where their
|
|
display environment supports it.
|
|
|
|
## Build and test
|
|
|
|
Initialize the bundled test library, then use the pinned Docker environment
|
|
for a reproducible build:
|
|
|
|
```sh
|
|
git submodule update --init
|
|
make docker-image
|
|
make docker-build
|
|
```
|
|
|
|
Build output:
|
|
|
|
```text
|
|
strans daemon with IBus and XIM frontends
|
|
gtk/im-strans.so GTK 3 frontend module
|
|
```
|
|
|
|
Tests have three tiers:
|
|
|
|
```sh
|
|
make check # generated-map validation and focused unit tests
|
|
make check-live # one IBus, GTK, XIM, and IPC daemon smoke
|
|
make check-stress # randomized, capacity, collision, failure, and restart tests
|
|
```
|
|
|
|
`UNITARGS` filters only the focused C unit suite, for example
|
|
`make check UNITARGS=hangul`. It does not select or skip live and stress
|
|
tests. `make docker-check` rebuilds and runs all three tiers in the
|
|
container, and `make docker-valgrind` runs the unit suite under Valgrind
|
|
there; run `make docker-image` first after changing `Dockerfile`.
|
|
|
|
Native Linux source builds require a C toolchain, Make, pkg-config, Python 3,
|
|
and cmp/diff, plus development files for:
|
|
|
|
- Plan 9 port (`9c`, `9l`, `libthread`, and `libbio`);
|
|
- D-Bus development files;
|
|
- XCB, XCB RandR, XCB XKB, xcb-util, xcb-imdkit, xkbcommon, and xkbcommon-x11;
|
|
- Pango, PangoCairo, Cairo, and Fontconfig;
|
|
- GTK 3, plus libibus and Xlib for the live clients;
|
|
- Xvfb for the X11 live tests;
|
|
- a working `C.UTF-8` locale and fonts covering Latin, CJK, and emoji.
|
|
|
|
The package names used by the canonical Arch Linux image are listed in
|
|
[`Dockerfile`](Dockerfile).
|
|
|
|
## Run
|
|
|
|
The popup uses the normal system fonts found by Pango and Fontconfig; no font
|
|
file argument or system-wide strans installation is required. Run it directly
|
|
from the build tree:
|
|
|
|
```sh
|
|
./run.sh
|
|
# equivalently
|
|
./strans map
|
|
```
|
|
|
|
`run.sh` stops every same-user process whose exact name is `strans`, starts one
|
|
build-tree daemon in the background, and returns to the shell. It requires
|
|
`pkill` from procps. Startup and frontend failures remain visible on the
|
|
caller's standard error. A service supervisor should instead run
|
|
`./strans map` directly in the foreground, with the session's
|
|
`XDG_RUNTIME_DIR` and `DISPLAY`: the GTK module finds the daemon at
|
|
`$XDG_RUNTIME_DIR/strans.sock` (else `/tmp/strans.UID`), and IBus clients
|
|
through the address file libibus expects under `~/.config/ibus/bus/`,
|
|
which strans writes as `ibus-daemon` would, named after `WAYLAND_DISPLAY`
|
|
when there is one and `DISPLAY` otherwise.
|
|
|
|
The build does not copy or install the daemon or its data. `./strans DIR`
|
|
opens `hira.map`, `kata.map`, `telex.map`, `kanji.dict`, `emoji.dict`, and
|
|
`hanja.dict` from `DIR` at runtime; `run.sh` passes the tracked `map/`
|
|
directory. Only the GTK subdirectory has install and uninstall targets.
|
|
|
|
Pango shapes the complete string and selects glyph fallback from the system
|
|
font set.
|
|
|
|
The popup renderer uses Pango/PangoCairo and Cairo. When `DISPLAY` is set,
|
|
`strans` starts its XIM worker in the same process.
|
|
|
|
Configure clients as needed:
|
|
|
|
```sh
|
|
# XIM
|
|
export XMODIFIERS=@im=strans
|
|
|
|
# GTK 3 module
|
|
doas make -C gtk install
|
|
export GTK_IM_MODULE=strans
|
|
|
|
# IBus client example
|
|
GLFW_IM_MODULE=ibus kitty
|
|
```
|
|
|
|
Building `gtk/im-strans.so` requires GTK development files. Installing an
|
|
already-built, up-to-date module from this build tree does not: the install
|
|
target first uses an explicit `GTK_MODULE_DIR`, then GTK's pkg-config
|
|
variables, and finally the module directory reported by the GTK runtime's
|
|
`gtk-query-immodules-3.0`. Packagers and cross builds should set
|
|
`GTK_MODULE_DIR` explicitly. A prebuilt module must still match the target
|
|
architecture and library ABI.
|
|
|
|
`DESTDIR` staging is supported and deliberately skips the host module-cache
|
|
update. A native install needs the GTK runtime query utility so it can refresh
|
|
that cache. Remove a native installation with:
|
|
|
|
```sh
|
|
doas make -C gtk uninstall
|
|
```
|
|
|
|
strans provides its own IBus endpoint; `ibus-daemon` and fcitx are not
|
|
required. IBus clients that process keys synchronously — GTK 4, or GTK 3
|
|
with `IBUS_ENABLE_SYNC_MODE=1` — get their commits and preedits through
|
|
`PostProcessKeyEvent`, in order with the key. Without `DISPLAY`, the daemon and IBus frontend still work, but XIM
|
|
is not started and the popup is disabled.
|
|
|
|
## Dictionary data
|
|
|
|
After changing an input source, regenerate and verify the maps and
|
|
dictionaries:
|
|
|
|
```sh
|
|
python3 map/mktelex.py >map/telex.map
|
|
map/mkemoji >map/emoji.dict
|
|
map/mkhanja >map/hanja.dict
|
|
make verify-map
|
|
```
|
|
|
|
See [`map/README`](map/README) for the emoji, Hanja, and Japanese data and
|
|
where it comes from.
|
|
|
|
## Benchmark
|
|
|
|
`make bench` builds `bench/bench`. With the daemon stopped, `./bench.sh` starts
|
|
one build-tree instance, warms it up, and records the workload with Linux
|
|
`perf`. It requires `perf` and permission to profile the daemon, and writes
|
|
`bench/perf.data`.
|
|
|
|
## Licensing
|
|
|
|
Third-party license notices are in [`LICENSES`](LICENSES). The repository does
|
|
not currently declare a license for the strans source as a whole.
|