From 279b9230a4d6d7cfae6888cedb0fd7bd58c27eb5 Mon Sep 17 00:00:00 2001 From: Hojun-Cho Date: Fri, 14 Aug 2026 13:43:45 +0900 Subject: [PATCH] docs: simplify README --- README.md | 243 +++++++++++++++--------------------------------------- 1 file changed, 66 insertions(+), 177 deletions(-) diff --git a/README.md b/README.md index 004e384..6da56f6 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,34 @@ # strans strans is a small, single-user input method for Korean, Japanese, English, -and emoji. It provides one engine shared by IBus, XIM, and GTK 3 frontends. -The existing Vietnamese Telex mode remains available for compatibility, but -is not an actively developed language mode. +emoji, and symbols. It provides one engine for IBus, XIM, and GTK 3. +Vietnamese Telex is also available as a compatibility mode. -## Input behavior +## Input modes -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. +| 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 | +| `Ctrl+P` | Toggle popup preedit | -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`. +Use `Up`/`Down` to move through candidates, `Enter` or `1`-`9` to select, +`Tab` to cycle temporary search results, and `Esc` to cancel. `0` commits the +current reading without conversion. -Modes and temporary searches use Ctrl and one letter: - -```text -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+H One-shot Hanja 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 temporary 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 → 😀 -``` - -Hanja search is temporary and returns to the active language after one -conversion. Press Ctrl+H and type with that language's normal input rules, -then select with Up, Down, Tab, Enter, or `1`-`9`. The bundled dictionary -currently indexes exactly one modern Hangul syllable. Incomplete jamo, -multiple syllables, and other languages therefore have no candidates; Enter -commits the displayed reading unchanged. Escape cancels the search. It does -not convert words or text already surrounding the cursor. +Hiragana mode composes a complete reading before offering Kanji candidates. +Katakana mode does not perform Kanji conversion. Emoji and Hanja searches +return to the previous mode after use. Hanja lookup currently supports one +modern Hangul syllable at a time. ## 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: +Docker is the supported build environment: ```sh git submodule update --init @@ -66,12 +37,7 @@ 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 targets force their own compilation, so newer host -objects cannot be reused. `docker` is a convenience alias for the image and -build steps. -The resulting runtime artifacts are: +Build output: ```text strans daemon and IBus frontend @@ -79,12 +45,44 @@ xim/strans-xim XIM frontend gtk/im-strans.so GTK 3 frontend ``` -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. +Use `make docker-check TESTARGS=hangul` to run selected C tests. Native +`make all`, `make check`, and `make bench` are also available when the +dependencies listed in [`Dockerfile`](Dockerfile) are installed. -After editing an input source, regenerate and verify its dictionary with: +## Run + +The popup needs one to four scalable font files. No fonts are bundled. +`run.sh` uses installed DejaVu, Jigmo, or Noto CJK fonts when available, or +accepts explicit files in fallback order: + +```sh +./run.sh +./run.sh /path/to/primary.ttf /path/to/fallback.ttc +``` + +The script starts the daemon and, when `DISPLAY` is set, the XIM frontend. It +restarts any existing `strans` processes owned by the current user. + +Configure clients as needed: + +```sh +# XIM +export XMODIFIERS=@im=strans + +# GTK 3 module +doas make -C gtk install + +# IBus client example +GLFW_IM_MODULE=ibus kitty +``` + +strans provides its own IBus endpoint; `ibus-daemon` and fcitx are not +required. Without `DISPLAY`, the daemon and IBus frontend still work, but the +popup is disabled. + +## Dictionary data + +After changing an input source, regenerate and verify the dictionaries: ```sh map/mkemoji >map/emoji.dict @@ -92,121 +90,12 @@ map/mkhanja >map/hanja.dict make verify-map ``` -Hanja import and Japanese dictionary regeneration are documented in -[`map/README`](map/README). The converter output is deterministic UTF-8, -tab-separated data consumable by the runtime dictionary reader. +See [`map/README`](map/README) for Hanja import and Japanese dictionary +generation. -## Run and install +## Licensing -Install one or more scalable outline fonts, then pass their files in fallback -order after the map directory. The daemon accepts at most four font files and -does not search the system font database. For example, the Docker-tested Arch -packages and paths are: - -```sh -doas pacman -S ttf-dejavu ttf-jigmo -./strans map \ - /usr/share/fonts/TTF/DejaVuSans.ttf \ - /usr/share/fonts/TTF/Jigmo.ttf \ - /usr/share/fonts/TTF/Jigmo2.ttf & -``` - -These fonts are test fixtures, not runtime requirements. Any suitable -scalable outline files may be supplied; their argument order is the glyph -fallback order. A collection file uses its first face. If any named file is -absent or invalid, the popup disables itself cleanly while input processing -continues. `run.sh` and `bench.sh` accept the same font-file arguments. -When `run.sh` is invoked without arguments, it uses the installed DejaVu, -Jigmo, or Noto CJK font files from the standard Arch Linux paths. Explicit -font-file arguments replace these defaults: - -```sh -./run.sh -./run.sh /path/to/primary.ttf /path/to/fallback.ttc -``` - -`run.sh` uses `pkill` to stop this user's existing `strans` and `strans-xim` -processes, starts fresh ones in the background, and returns. Run the same -command again to restart them. Without `DISPLAY`, it starts only the daemon. - -An X startup hook can invoke it directly before starting the desktop session: - -```sh -/path/to/strans/run.sh -exec /bin/sh /etc/xdg/xfce4/xinitrc "$@" -``` - -The launcher targets Linux and requires `pkill` from procps-ng. - -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.`. A second daemon will not replace a live -daemon's socket. - -For XIM applications: - -```sh -./xim/strans-xim & -export XMODIFIERS=@im=strans -xterm -``` - -For GTK 3 applications, install the module built by Docker. Installation -needs the GTK 3 runtime, but not its development package: - -```sh -doas make -C gtk install -``` - -`LIBDIR` defaults to `/usr/lib` and may be overridden for another system. -Normal `DESTDIR` semantics are supported, and a staged install does not update -the host GTK module cache: - -```sh -make -C gtk install DESTDIR="$pkgdir" -``` - -For IBus clients such as kitty: - -```sh -GLFW_IM_MODULE=ibus kitty -``` - -strans provides its own IBus endpoint; neither ibus-daemon nor fcitx is -required. Starting without `DISPLAY` is supported: input processing and IBus -continue to run while the optional X popup is disabled. - -## Ownership and rendering constraints - -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. - -The popup is an optional X window. It uses the explicit font-file order 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. 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. - -## Data, third-party code, and licensing - -Data and third-party provenance is recorded in -[`docs/PROVENANCE.md`](docs/PROVENANCE.md), with font-specific details in -[`font/PROVENANCE`](font/PROVENANCE). No font binaries are bundled; that file -retains the provenance of the faces formerly kept in the repository. 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). -The single-character Hanja data derived from libhangul is distributed under -the BSD 3-Clause license in -[`LICENSES/BSD-3-Clause-libhangul-hanja.txt`](LICENSES/BSD-3-Clause-libhangul-hanja.txt). - -The repository does not currently declare a license for the strans project -source as a whole. The licenses of bundled data, historical font assets, and -third-party components do not by themselves license the original strans -source. +Data and third-party notices are in +[`docs/PROVENANCE.md`](docs/PROVENANCE.md) and +[`font/PROVENANCE`](font/PROVENANCE). The repository does not currently +declare a license for the strans source as a whole.