strans/README.md

# 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.

## Input behavior

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.

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`.

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.

## 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 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:

```text
strans              daemon and IBus frontend
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.

After editing an input source, regenerate and verify its dictionary with:

```sh
map/mkemoji >map/emoji.dict
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.

## Run and install

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.

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
./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.