docs: record data provenance and runtime constraints
This commit is contained in:
178
README.md
178
README.md
@@ -1,47 +1,103 @@
|
||||
# strans
|
||||
|
||||
A small input method daemon for Japanese, Korean, Vietnamese, emoji, and
|
||||
symbols on X11 and Wayland. Inspired by 9front's ktrans.
|
||||
strans is a small, single-user input method for Korean, Japanese, English,
|
||||
and emoji on X11 and Wayland. It provides one engine shared by XIM, GTK 3,
|
||||
IBus, and Wayland input-method-v2 frontends. The existing Vietnamese Telex
|
||||
mode remains available for compatibility, but is not an actively developed
|
||||
language mode.
|
||||
|
||||
## Build
|
||||
## Input behavior
|
||||
|
||||
The recommended build needs only Docker and Make on the host:
|
||||
English is direct passthrough. Korean uses 2-beolsik composition. Japanese
|
||||
Hiragana keeps the complete kana reading until it is committed, so `kanji`
|
||||
forms `かんじ` and offers whole-reading candidates such as `漢字` and `幹事`.
|
||||
An apostrophe resolves an ambiguous `n` without forwarding the apostrophe:
|
||||
for example, `n'ya` forms `んや`. Katakana is direct Katakana composition
|
||||
and does not perform Kanji dictionary conversion.
|
||||
|
||||
```sh
|
||||
make docker
|
||||
```
|
||||
A Japanese composition is committed by Enter, candidate selection, a real
|
||||
input boundary, or an explicit mode change. Backspace first removes pending
|
||||
romaji, then accumulated kana. The Japanese modes support doubled consonants
|
||||
and combinations such as `nya`, `nnya`, and `matcha`.
|
||||
|
||||
This creates an Arch Linux build image, compiles all runtime components in one
|
||||
disposable container, and writes three artifacts into the source tree:
|
||||
Modes are selected with Ctrl and one letter:
|
||||
|
||||
```text
|
||||
strans daemon, IBus and Wayland frontend
|
||||
Ctrl+N Japanese Hiragana and Kanji conversion
|
||||
Ctrl+K Japanese Katakana
|
||||
Ctrl+S Korean Hangul
|
||||
Ctrl+T English passthrough
|
||||
Ctrl+V Vietnamese Telex compatibility mode
|
||||
Ctrl+E Emoji and symbol search
|
||||
Ctrl+P Toggle popup preedit
|
||||
```
|
||||
|
||||
While candidates are visible, Up and Down move the selection, Enter accepts
|
||||
the selected candidate, and an unmodified `1`-`9` selects the corresponding
|
||||
visible row. Tab cycles emoji search results. `0` commits an unconverted
|
||||
language reading. Escape cancels the current composition. Ctrl, Alt, or
|
||||
Super combined with a number does not select a candidate.
|
||||
|
||||
Emoji search is temporary and returns to the previous mode. Queries may use
|
||||
English aliases or the active language's input rules, including Japanese
|
||||
`egao` becoming `えがお` or `エガオ`:
|
||||
|
||||
```text
|
||||
Ctrl+E → smile → Enter → 😀
|
||||
```
|
||||
|
||||
## Build and test
|
||||
|
||||
The supported build uses Docker so host and container toolchains are not
|
||||
mixed. Only Docker and Make are needed on the host:
|
||||
|
||||
```sh
|
||||
git submodule update --init
|
||||
make docker-image
|
||||
make docker-build
|
||||
make docker-check
|
||||
```
|
||||
|
||||
`docker-image` creates the Arch Linux dependency image, `docker-build`
|
||||
compiles the runtime components, and `docker-check` runs the map verifiers and
|
||||
test suites. `docker` is a convenience alias for the image and build steps.
|
||||
The resulting runtime artifacts are:
|
||||
|
||||
```text
|
||||
strans daemon, IBus and Wayland frontends
|
||||
xim/strans-xim XIM frontend
|
||||
gtk/im-strans.so GTK 3 frontend
|
||||
```
|
||||
|
||||
The build starts clean so host and container object files are never mixed. It
|
||||
removes existing build and test outputs; the `strans-build` dependency image is
|
||||
kept as a cache. No development packages are required on the host.
|
||||
Use `make docker-check TESTARGS=hangul` to filter the C unit tests. A native
|
||||
build is still possible with the dependencies and Plan 9 setup recorded in
|
||||
`Dockerfile`; use `make all`, `make check`, and `make bench` inside that
|
||||
environment.
|
||||
|
||||
Void Linux runtime dependencies:
|
||||
After editing `map/emoji.src`, regenerate and verify its dictionary with:
|
||||
|
||||
```sh
|
||||
sudo xbps-install -S dbus-libs wayland libxkbcommon libxcb xcb-imdkit gtk+3
|
||||
map/mkemoji >map/emoji.dict
|
||||
make verify-map
|
||||
```
|
||||
|
||||
For a native Arch Linux build, use `Dockerfile` as the dependency and Plan 9
|
||||
setup checklist, then run `make`. Build the benchmark separately with
|
||||
`make bench`.
|
||||
Japanese dictionary regeneration and verification are documented in
|
||||
[`map/README`](map/README). The converter output is deterministic UTF-8,
|
||||
tab-separated data consumable by the runtime dictionary reader.
|
||||
|
||||
## Run
|
||||
## Run and install
|
||||
|
||||
Start the daemon:
|
||||
Start the daemon with the installed map and font directories:
|
||||
|
||||
```sh
|
||||
./strans map font &
|
||||
```
|
||||
|
||||
The IPC socket is placed at `$XDG_RUNTIME_DIR/strans.sock` when
|
||||
`XDG_RUNTIME_DIR` is an absolute path. Otherwise strans uses the per-user
|
||||
fallback `/tmp/strans.<uid>`. A second daemon will not replace a live
|
||||
daemon's socket.
|
||||
|
||||
For XIM applications:
|
||||
|
||||
```sh
|
||||
@@ -50,11 +106,11 @@ export XMODIFIERS=@im=strans
|
||||
xterm
|
||||
```
|
||||
|
||||
For GTK 3 applications:
|
||||
For GTK 3 applications, install with normal `DESTDIR` semantics. A staged
|
||||
install does not update the host GTK module cache:
|
||||
|
||||
```sh
|
||||
sudo make -C gtk install
|
||||
GTK_IM_MODULE=strans gedit
|
||||
make -C gtk install DESTDIR="$pkgdir"
|
||||
```
|
||||
|
||||
For IBus clients such as kitty:
|
||||
@@ -63,56 +119,38 @@ For IBus clients such as kitty:
|
||||
GLFW_IM_MODULE=ibus kitty
|
||||
```
|
||||
|
||||
Wayland needs no environment variable. Start `strans` after a wlroots
|
||||
compositor that supports input-method-v2. Neither ibus-daemon nor fcitx is
|
||||
required.
|
||||
Wayland needs no environment variable. Start `strans` after a compositor
|
||||
that supports input-method-v2. Neither ibus-daemon nor fcitx is required.
|
||||
Starting without `DISPLAY` is supported: the optional X popup is disabled,
|
||||
while input processing and non-X frontends continue to run.
|
||||
|
||||
## Keys
|
||||
## Ownership and rendering constraints
|
||||
|
||||
Input modes are selected with Ctrl and one letter:
|
||||
There is one global composition, not one independent engine per frontend
|
||||
context. The first meaningful key from a new context resets the previous
|
||||
composition and transfers ownership. Reset, focus loss, context destruction,
|
||||
and disconnect affect the engine only when they come from its active owner;
|
||||
stale events cannot clear a newer owner's preedit.
|
||||
|
||||
```text
|
||||
Ctrl+N Hiragana
|
||||
Ctrl+K Katakana
|
||||
Ctrl+S Hangul
|
||||
Ctrl+T English
|
||||
Ctrl+V Vietnamese Telex
|
||||
Ctrl+E Emoji and symbol search
|
||||
Ctrl+P Toggle popup preedit
|
||||
```
|
||||
The popup is an optional X window, including when the active frontend is
|
||||
Wayland. It uses deterministic font fallback and fixed-width rune cells;
|
||||
U+FE0E and U+FE0F variation selectors use zero cells. It does not perform
|
||||
OpenType shaping, color-emoji rendering, or general grapheme clustering, and
|
||||
there is no native Wayland popup renderer. Multi-rune emoji are committed
|
||||
intact but are drawn as their constituent rune cells under this boundary. A
|
||||
supplied caret rectangle is used when available, with the pointer as fallback.
|
||||
The X renderer accepts only a 24-depth, 32-bpp TrueColor root format and
|
||||
disables itself cleanly on other visuals.
|
||||
|
||||
Use `1`-`9` or the arrow keys to select a candidate. Tab moves through
|
||||
candidates, Enter commits, and Escape cancels.
|
||||
## Data, third-party code, and licensing
|
||||
|
||||
Emoji search is temporary and returns to the previous input mode:
|
||||
Data and third-party provenance is recorded in
|
||||
[`docs/PROVENANCE.md`](docs/PROVENANCE.md), with font-specific details in
|
||||
[`font/PROVENANCE`](font/PROVENANCE). The historical SKK-derived Kanji
|
||||
dictionary is distributed under GPL version 2 or later; its license text is
|
||||
in [`LICENSES/GPL-2.0-or-later.txt`](LICENSES/GPL-2.0-or-later.txt).
|
||||
|
||||
```text
|
||||
Ctrl+E → smile → Enter → 😀
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
Tests use the sibling `cutest` repository as a submodule. Its relative URL
|
||||
expects repository mirrors and forks to provide the same sibling. Initialize
|
||||
it once, then run the checks in the build container:
|
||||
|
||||
```sh
|
||||
git submodule update --init
|
||||
make docker-check
|
||||
```
|
||||
|
||||
The native `make check` command needs plan9port and Python 3, but not the GUI
|
||||
development packages. Use `make test TESTARGS=hangul` or
|
||||
`make docker-check TESTARGS=hangul` to filter unit tests. After editing
|
||||
`map/emoji.src`, regenerate and verify the dictionary with:
|
||||
|
||||
```sh
|
||||
map/mkemoji > map/emoji.dict
|
||||
make verify-map
|
||||
```
|
||||
|
||||
## Design
|
||||
|
||||
`strans` owns the input engine and candidate window. The XIM and GTK frontends
|
||||
forward keys to it over a Unix socket; the IBus and Wayland frontends are built
|
||||
into the daemon. Internal threads communicate through CSP channels.
|
||||
The repository does not currently declare a license for the strans project
|
||||
source as a whole. The licenses of bundled data, fonts, generated protocol
|
||||
code, and third-party components do not by themselves license the original
|
||||
strans source.
|
||||
|
||||
Reference in New Issue
Block a user