Hojun-Cho/strans
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: simplify README

Browse Source
This commit is contained in:
Hojun-Cho
2026-08-14 13:43:45 +09:00
parent c2cb18cbdd
commit 279b9230a4
1 changed files with 66 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
README.md
View File

@@ -1,63 +1,34 @@
# strans # strans
strans is a small, single-user input method for Korean, Japanese, English, 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. emoji, and symbols. It provides one engine for IBus, XIM, and GTK 3.
The existing Vietnamese Telex mode remains available for compatibility, but Vietnamese Telex is also available as a compatibility mode.
is not an actively developed language mode.
## Input behavior ## Input modes
English is direct passthrough. Korean uses 2-beolsik composition. Japanese | Key | Mode |
Hiragana keeps the complete kana reading until it is committed, so `kanji` | --- | --- |
forms `かんじ` and offers whole-reading candidates such as `漢字` and `幹事`. | `Ctrl+N` | Japanese Hiragana and Kanji conversion |
An apostrophe resolves an ambiguous `n` without forwarding the apostrophe: | `Ctrl+K` | Japanese Katakana |
for example, `n'ya` forms `んや`. Katakana is direct Katakana composition | `Ctrl+S` | Korean Hangul (2-beolsik) |
and does not perform Kanji dictionary conversion. | `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 Use `Up`/`Down` to move through candidates, `Enter` or `1`-`9` to select,
input boundary, or an explicit mode change. Backspace first removes pending `Tab` to cycle temporary search results, and `Esc` to cancel. `0` commits the
romaji, then accumulated kana. The Japanese modes support doubled consonants current reading without conversion.
and combinations such as `nya`, `nnya`, and `matcha`.
Modes and temporary searches use Ctrl and one letter: Hiragana mode composes a complete reading before offering Kanji candidates.
Katakana mode does not perform Kanji conversion. Emoji and Hanja searches
```text return to the previous mode after use. Hanja lookup currently supports one
Ctrl+N Japanese Hiragana and Kanji conversion modern Hangul syllable at a time.
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 ## Build and test
The supported build uses Docker so host and container toolchains are not Docker is the supported build environment:
mixed. Only Docker and Make are needed on the host:
```sh ```sh
git submodule update --init git submodule update --init
@@ -66,12 +37,7 @@ make docker-build
make docker-check make docker-check
``` ```
`docker-image` creates the Arch Linux dependency image, `docker-build` Build output:
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 ```text
strans daemon and IBus frontend strans daemon and IBus frontend
@@ -79,12 +45,44 @@ xim/strans-xim XIM frontend
gtk/im-strans.so GTK 3 frontend gtk/im-strans.so GTK 3 frontend
``` ```
Use `make docker-check TESTARGS=hangul` to filter the C unit tests. A native Use `make docker-check TESTARGS=hangul` to run selected C tests. Native
build is still possible with the dependencies and Plan 9 setup recorded in `make all`, `make check`, and `make bench` are also available when the
`Dockerfile`; use `make all`, `make check`, and `make bench` inside that dependencies listed in [`Dockerfile`](Dockerfile) are installed.
environment.
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 ```sh
map/mkemoji >map/emoji.dict map/mkemoji >map/emoji.dict
@@ -92,121 +90,12 @@ map/mkhanja >map/hanja.dict
make verify-map make verify-map
``` ```
Hanja import and Japanese dictionary regeneration are documented in See [`map/README`](map/README) for Hanja import and Japanese dictionary
[`map/README`](map/README). The converter output is deterministic UTF-8, generation.
tab-separated data consumable by the runtime dictionary reader.
## Run and install ## Licensing
Install one or more scalable outline fonts, then pass their files in fallback Data and third-party notices are in
order after the map directory. The daemon accepts at most four font files and [`docs/PROVENANCE.md`](docs/PROVENANCE.md) and
does not search the system font database. For example, the Docker-tested Arch [`font/PROVENANCE`](font/PROVENANCE). The repository does not currently
packages and paths are: declare a license for the strans source as a whole.
```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.<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.