docs: simplify README
This commit is contained in:
243
README.md
243
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.<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.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user